MkDocsサイトを S3へデプロイする GitHub Actions ワークフローを作ってみる

川原征大

2022.05.06

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

MkDocs による静的サイトを S3バケットへデプロイする GitHubワークフローを作成してみました。手順をまとめます。

下図にざっくりとした流れを記載しています。

MkDocsとは

MkDocs は静的サイトジェネレーターです。ドキュメントのソースを Markdownで記述します。ページ構成やテーマなどの設定は YAMLファイルで指定、幅広いカスタマイズが可能です。 GitHub Pages や S3バケット(今回のターゲット)へデプロイして、公開することもできます。

※MkDocs の詳しい使い方やチューニングについては以下記事を参照ください。

プロジェクトドキュメント構築向け静的サイトジェネレータ『MkDocs』及び『Material for MkDocs』の個人的導入＆設定まとめ | DevelopersIO

S3へのデプロイワークフローを作成する

※ Sphinx (静的サイトジェネレーター) ドキュメントを S3へデプロイしている以下ブログを大いに参考にしています。

GitHub ActionsワークフローでSphinxドキュメントをS3へデプロイする | DevelopersIO

S3バケットの作成

事前にデプロイ先の S3バケットを準備します。

GitHub リポジトリの作成

Getting Started - MkDocs どおりにサンプルドキュメントを作成、これを GitHubリポジトリへプッシュしておきます。 (ローカルのテストで mkdocs build したときに作られる site/ ディレクトリは .gitignore に入れておくと良いでしょう)

(参考) ファイル構成は以下のようになりました。

$ tree -L 2
.
├── docs
│   ├── about.md
│   └── index.md
└── mkdocs.yml

site_name: MkLorum
site_url: https://example.com/
nav:
    - Home: index.md
    - About: about.md
theme: readthedocs

GitHub OIDCプロバイダー設定

IDプロバイダーの作成
IAMロールの作成

を行います。ここの設定は以下ブログによくまとまっています。そちらを参照ください。

GitHub Actions OIDCでconfigure-aws-credentialsでAssumeRoleする | DevelopersIO

IAMロールの権限は以下のとおりです。 (今回は検証のため、Action 部分は s3:* としています。 s3 sync で使用する権限に絞ることも可能です)

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::${S3バケット名}",
                "arn:aws:s3:::${S3バケット名}/*"
            ]
        }
    ]
}

GitHub ワークフロー作成

以下のようなワークフローを作成しました。

今回は手動実行とするために on: workflow_dispatch と記載しています。

name: Sync Mkdocs build to S3
on: workflow_dispatch
env:
  BUCKET_NAME : "${バケット名}"
  AWS_REGION : "ap-northeast-1"
  AWS_ROLE_ARN: "arn:aws:iam::${AWSアカウントID}:role/${IAMロール名}"
permissions:
  id-token: write
  contents: read
jobs:
  Sync:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v3

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: ${{ env.AWS_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Setup Python
        uses: actions/setup-python@v3
        with:
          python-version: '3.9'
          architecture: 'x64'

      - name: Install MkDocs
        run: |
          pip install -U mkdocs

      - name: Build
        run: |
          mkdocs build

      - name: Sync html to s3
        run: |
          aws s3 sync ./site s3://${{ env.BUCKET_NAME }}/site --delete --quiet

大枠はこちらの Sphinx ブログとほぼ同じです。 mkdocs の場合はビルドコマンドが mkdocs build 、ビルドしたときの成果物が (デフォルトで) site となります。